---
title: Getting started
slug: /
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Interweave is a robust React library that can...

- Safely render HTML without using `dangerouslySetInnerHTML`.
- Safely strip HTML tags.
- Automatic XSS and injection protection.
- Clean HTML attributes using filters.
- Interpolate components using matchers.
- Autolink URLs, IPs, emails, and hashtags.
- Render Emoji and emoticon characters.
- And much more!

## Requirements

- React 16.8+ / 17+
- IE 11+
- Emoji support: `fetch`, `sessionStorage`

## Installation

<Tabs
  groupId="package-manager"
  defaultValue="yarn"
  values={[
    { label: 'Yarn', value: 'yarn' },
    { label: 'NPM', value: 'npm' },
  ]}
>
  <TabItem value="yarn">

```bash
yarn add interweave react
```

  </TabItem>
  <TabItem value="npm">

```bash
npm install interweave react
```

  </TabItem>
</Tabs>

## Why is it safe?

Interweave is deemed safe as it doesn't rely on custom HTML parsers (excluding SSR) -- it relies on
the browser and DOM itself for parsing. Because of this, we take full control of the parsing flow by
inspecting all HTML elements and their attributes, and then filtering problematic values, avoiding
vulnerabilities, and closing XSS holes.

We also take this a step further by maintaing an explicit allow, block, and banned list of HTML
elements and attributes. Interweave has also been penetration tested multiple times with _zero_
issue!

## Usage

Interweave can primarily be used with the `<Interweave />` and `<Markup />` components, both of
which provide an easy, straight-forward implementation for safely
[parsing and rendering HTML](parser.md).

### `<Interweave />`

The `Interweave` component has the additional benefit of utilizing [filters](filters.mdx),
[matchers](matchers.mdx), and callbacks.

```tsx
import { Interweave } from 'interweave';

<Interweave content="This string contains <b>HTML</b> and will safely be rendered!" />;

<Interweave
	content="This contains a URL, https://github.com/milesj/interweave, and a hashtag, #interweave, that will be converted to an anchor link!"
	matchers={[new UrlMatcher('url'), new HashtagMatcher('hashtag')]}
/>;
```

### `<Markup />`

Unlike the `Interweave` component, the `Markup` component does not support matchers, filters, or
callbacks. This component is preferred when rendering strings that contain HTML is the only use
case.

```tsx
import { Markup } from 'interweave';

<Markup content="This string <b>contains</b> HTML." />;
```

### Props

_Markup & Interweave_

- `allowAttributes` (`boolean`) - Disable filtering and allow all non-banned HTML attributes.
- `allowElements` (`boolean`) - Disable filtering and allow all non-banned/blocked HTML elements to
  be rendered.
- `allowList` (`string[]`) - List of HTML tag names to allow and render. Defaults to the
  `ALLOWED_TAG_LIST` constant.
- `attributes` (`Record<string, boolean | number | object | string>`) - HTML attributes to pass to the wrapping element.
- `blockList` (`string[]`) - List of HTML tag names to disallow and not render. Overrides allow
  list.
- `containerTagName` (`string`) - The container element to parse content in. Applies browser
  semantic rules and overrides `tagName`.
- `className` (`string`) - CSS class name to pass to the wrapping element.
- `content` (`string`) - The string to render and apply matchers and filters to. Supports HTML.
- `disableLineBreaks` (`boolean`) - Disables automatic line break conversion.
- `emptyContent` (`Node`) - React node to render if no content was rendered.
- `escapeHtml` (`boolean`) - Escape all HTML in the content before parsing.
- `noHtml` (`boolean`) - Strips HTML tags from the content string while parsing. Also strips HTML
  generated by matchers.
- `noHtmlExceptMatchers` (`boolean`) - Like the former, but allows HTML generated by matchers.
- `noWrap` (`boolean`) - Do not wrap the content in an HTML element (uses React fragments).
- `tagName` (`string`) - The HTML element tag name to wrap the output with. Defaults to "span".
- `transform` (`func`) - Callback that fires during parsing. Is passed the parsed DOM node, and can
  return an element, null to skip the node, or undefined to use the default element.
- `transformOnlyAllowList` (`boolean`) - Disables the `transform` function for tags not present in
  the `allowList`.

_Interweave only_

- `disableFilters` (`boolean`) - Disables all filters.
- `disableMatchers` (`boolean`) - Disables all matchers.
- `filters` (`Filter[]`) - Filters to apply to this instance.
- `matchers` (`Matcher[]`) - Matchers to apply to this instance.
- `onBeforeParse` (`func`) - Callback that fires before parsing. Is passed the source string and
  must return a string.
- `onAfterParse` (`func`) - Callback that fires after parsing. Is passed an array of
  strings/elements and must return an array.
  